Расширение Plesk представляет собой архив ZIP, который содержит организованную специальным образом структуру папок и файл с метаданными, описывающими программное обеспечение. Начиная с Plesk 11, разработчики могут упаковывать расширения в кроссплатформенном формате — в виде архива ZIP, в котором файл метаданных находится в корневой папке. Такие расширения поддерживаются Plesk для Linux и для Windows.

Структура файлов

Типичный архив ZIP с расширением имеет следующую структуру файлов и папок:

example-extension.zip
 |
 +-meta.xml
 +-DESCRIPTION.md
 +-CHANGES.md
 +-/sbin/
 +-/htdocs/
    |
    +-index.php
    +-public/
    +-...
 +-/plib/
    |
    +--controllers
    |         IndexController.php
    |
    +---scripts
    |         post-install.php
    |         pre-install.php
    |         pre-uninstall.php
    |
    +---views
    |    \---scripts
    |         \---index
    |                    index.phtml
    |
    +-/hooks/
      |
      +-...
    +-/library/
      |
      +-...
 +-/var/
    |
    +-...
 +-/_meta/
    |
    +-...

Ниже описаны наиболее важные файлы и папки:

meta.xml — описание расширения в формате XML. Во время установки расширения этот файл извлекается в PRODUCT_ROOT_D/admin/plib/modules/EXTENSION_ID/meta.xml, где PRODUCT_ROOT_D — это /usr/local/psa в системах Linux и %plesk_dir% — в системах Windows. Смотрите подробное описание структуры этого файла.

DESCRIPTION.md — расширенное описание расширения. Расширение должно быть написано на языке Markdown. Больше информации можно найти в подробном описании этого файла.

CHANGES.md — журнал изменений расширения. Журнал изменений должен быть написан на языке Markdown. Больше информации можно найти в подробном описании этого файла.

/sbin/ — эта папка должна содержать скрипты, которые во время выполнения требуют привилегий более высокого уровня.

/htdocs — все точки входа расширения, CSS, Javascript и все графические файлы должны быть помещены в эту папку. Во время установки расширения содержимое этой папки извлекается непосредственно в папку /PRODUCT_ROOT_DIR/admin/htdocs/modules/EXTENSION_ID/.

/htdocs/public — содержит скрипты, которые не требуют авторизации (обходные контроллеры). Например, если ваше расширение предоставляет свое API.

/plib — эта папка должна содержать классы PHP, которые отвечают за логику расширения. Во время установки расширения содержимое этой папки извлекается непосредственно в папку PRODUCT_ROOT_D/admin/plib/modules/MODULE_ID/.

/plib/conrollers — эта папка должна содержать контроллеры расширения (более подробную информацию смотрите в описании шаблона MVC). Эта папка автоматически создается при создании расширения и содержит контроллер по умолчанию для обработки запросов IndexController.php.

/plib/library — эта папка должна содержать файлы, реализующие логику расширения. Классы из этой папки загружаются автоматически. Более подробную информацию смотрите в Соглашениях по именованию классов.

/plib/scripts — эта папка должна содержать скрипты, которые система запускает непосредственно перед установкой расширения, после установки расширения и перед его удалением.

Доступны следующие скрипты:

pre-install.php — запускается перед копированием файлов расширения. Этот скрипт позволяет убедиться, что система отвечает всем требованиям расширения и не выполняет никаких изменений на сервере. На этой стадии файлы расширения недоступны.

post-install.php — запускается после копирования файлов расширения. Этот скрипт подготавливает систему для установки расширения и выполняет все изменения, необходимые для работы расширения. С помощью этого скрипта мы можем, например, создать базы данных или подготовить необходимую структуру папок.

pre-uninstall.php — запускается перед удалением расширения. Этот скрипт помогает удалить файлы, используемые расширением, такие как базы данных, шаблоны и контент пользователей. Кроме того, перед удалением расширение должно откатить все изменения, выполненные на сервере (например, если расширение вносит изменения в конфигурационные файлы, эти изменения необходимо откатить).

Если скрипт прекращает работу с ненулевым статусом, выполняемое действие прерывается с ошибкой. В выводе скрипта администратор Plesk увидит сообщение об ошибке.

Кроме того, вы можете использовать папку /plib/scripts для хранения ваших персональных скриптов. Например, многие авторы расширений помещают в нее скрипты, которые позже будут запущены как запланированные задачи.

/plib/views — эта папка содержит представления расширения, которые определяют, как именно данные будут показаны пользователю (читайте больше о представлениях здесь). Эта папка автоматически создается при создании расширения и содержит файл представления по умолчанию scripts/index/index.phtml.

/plib/hooks — эта папка должна содержать хуки Plesk (точки интеграции, такие как персональные кнопки и авторизация).

/var — папка для хранения данных, используемых расширением, например, баз данных SQLite. Во время установки расширения содержимое этой папки извлекается в PRODUCT_ROOT_D/var/modules/EXTENSION_ID/. Эта папка не удаляется при обновлении расширения.

/_meta — эта папка содержит значки и снимки экрана расширения.

meta.xml

Вот пример файла meta.xml, описывающего расширение с названием «Тестовое расширение».

<?xml version="1.0"?>
<module>
  <id>test-extension</id>
  <name>Test extension</name>
  <description>Add description here...</description>
  <category>example</category>
  <category>help</category>
  <buy_url>https://example.com/</buy_url>
  <version>1.0</version>
  <release>1</release>
  <vendor>Plesk</vendor>
  <url>https://your-company-website</url>
  <help_url>https://your-company-website/documentation</help_url>
  <support_url>https://your-company-website/support</support_url>
  <plesk_min_version>12.5.0</plesk_min_version>
</module>

Ниже описаны элементы, доступные внутри узла module:

  • id

    Идентификатор расширения. Он используется как часть URL-адреса корня расширения. Например, если ID расширения — sample-extension, расширение доступно по адресу http://<plesk-host-name>:<port>/modules/sample-extension.

    • Составьте ID на основании выбранного названия расширения (читайте о нем ниже). Имейте в виду, что ID расширения — часть его URL-адреса в каталоге, поэтому использование уникальных значимых слов может способствовать его более эффективному продвижению в поисковых системах (SEO).
    • Все слова должны быть введены в нижнем регистре.
    • Разделяйте слова с помощью тире.

  • name

    Название, которое администраторы увидят в списке расширений в Plesk (Управление сервером > Расширения) после установки расширения.

    • Выберите название короче 60 символов. Предпочтительная длина — 25 символов или менее, чтобы название гарантированно полностью помещалось в заголовок рекламного блока на сайте.
    • Название должно быть на английском языке. Использование других языков рекомендуется, но необязательно.
    • Избегайте слов, которые не добавляют уникальной значимой информации, например: extension, plugin, Plesk, installer, integration и так далее.

  • description

    Описание расширения, которое администраторы увидят в списке расширений в Plesk (Управление сервером > Расширения) после установки расширения.

  • category

    Категория или категории, к которым относится расширение. Пользователи могут сортировать расширения в Каталоге расширений по категории, поэтому присвоение вашему расширению правильной категории или категорий может увеличить количество его просмотров. Вы можете указать более одной категории для своего расширения, но каждая из них должна быть введена с новой строки и помечена своим набором тэгов. Обратите внимание, что, присваивая расширению категорию, вы должны указать в файле meta.xml код категории, а не ее удобочитаемое название. В таблице ниже представлен полный список доступных категорий и их кодов.

    Название категории (удобочитаемое) Код категории (указывается в файле meta.xml)
    Внешний вид appearance
    Аутентификация auth
    Резервное копирование backup
    Бета-версия beta
    Инструменты клиента client_tool
    Облака clouds
    CRM crm
    DNS dns
    Примеры example
    Пакеты функций feature_pack
    Развлечения fun
    Помощь и решение проблем help
    Почта mail
    Мониторинг monitoring
    Безопасность security
    Серверные инструменты server_tool
    SEO и социальные сети social
    Веб-приложения и редактирование сайтов web_app
    Веб-разработка developer
    Веб-серверы webserver
    Производительность сайтов performance

  • version

    Версия расширения (строка). Мы рекомендуем вам использовать формат версии X.Y.Z, например, 1.0.2. Администратор может посмотреть версию расширения в Каталоге расширений.

  • release

    Версия пакета расширения. Она относится к изменениям, которые не затрагивают код расширения, но меняют что-либо в самом пакете (например, послеустановочный скрипт). Может быть произвольной строкой, но мы рекомендуем использовать следующий формат: X (где X ? число), например, 1. Администраторы могут видеть ее в списке расширений.

  • vendor

    Имя поставщика.

  • url

    Сайт поставщика расширения.

  • support_url

    Ссылка на страницу службы поддержки поставщика расширения. Администраторы могут видеть ее на странице расширения в Каталоге расширений. Наличие URL-адреса службы поддержки обязательно для платных расширений.

  • help_url

    Ссылка на документацию к расширению. Администраторы могут видеть ее в списке расширений.

  • buy_url (необязательно)

    URL-адрес сайта или интернет-магазина, где можно купить лицензию на расширение. Расширению может требоваться лицензия для работы некоторых или всех функций. Указание URL-адреса приведет к появлению кнопки «Купить сейчас» рядом с именем расширения в Каталоге расширений. При нажатии этой кнопки в окне браузера откроется указанный URL-адрес. Имейте в виду, что платные расширения должны содержать ссылку на страницу службы поддержки поставщика расширения ? смотрите описание support_url выше.

    Значение по умолчанию для buy_url — следующий URL-адрес: https://go.plesk.com/buy-plesk-ext/<id>, где id ? идентификатор вашего расширения (смотрите описание id выше).

  • plesk_min_version (необязательно)

    Минимальная версия Plesk, поддерживаемая расширением.

    Выбор минимальной поддерживаемой версии Plesk обычно зависит от используемой версии Plesk SDK.

    Примечание: Готовое расширение необходимо тщательно протестировать на всех поддерживаемых версиях Plesk, чтобы удостовериться в том, что оно работает правильно и не зависит от различий в версиях ядра и SDK.

  • plesk_max_version (необязательно)

    Максимальная версия Plesk, поддерживаемая расширением.

    Этот параметр полезен в случае наличия известных или вероятных проблем при работе с версиями Plesk выше указанной. Например, если в этих версиях была добавлена поддержка новой версии PHP, и это может каким-либо образом нарушить работу.

  • os (необязательно)

    Операционные системы, поддерживаемые расширением. Возможные значения: unix (для Linux) и win (для Windows).

Локализация элементов

Чтобы перевести значение элемента на другой язык, продублируйте его и добавьте атрибут xml:lang с 4-буквенным кодом языка в соответствии с RFC1766. Например:

<description>Easily add customers and websites</description>
<description xml:lang="de-DE">Einfache Neukundenerfassung & simple Website-Erstellung</description>

DESCRIPTION.md

Прежде чем загрузить расширение, администраторы Plesk хотят видеть подробное описание его функциональности и ограничений. Это особенно актуально в случае, когда есть несколько расширений от различных поставщиков, которые выполняют одну и ту же задачу или занимают одну и ту же нишу.

Используйте файл DESCRIPTION.md, чтобы сообщить администраторам Plesk о том, какие функции предоставляет ваше расширение и какие задачи оно помогает выполнять. Если расширение имеет ограничения или требует покупки лицензии для разблокировки некоторых или всех своих функций, удостоверьтесь, что информация об этом добавлена в файл.

Файл DESCRIPTION.md находится в корневой папке расширения. В файле DESCRIPTION.md должен использоваться английский язык.

Локализация описания расширения

Перевод описания вашего расширения на разные языки позволит большему количеству людей заметить ваше расширение.

Примечание: Эта опция возможна, начиная с Plesk 17.8.

Для переводов описаний расширений создаются отдельные файлы описаний.

  • Файлы описаний имеют формат Markdown (.md).
  • Файлы описаний хранятся в папке /_meta/descriptions/.
  • Можно создать несколько файлов описаний, по одному для каждой локали. В зависимости от текущей локали Plesk, будет выбираться нужный файл.
  • Имя файла описания соответствует идентификатору его локали: en-US.md, de-DE.md, ru-RU.md и так далее.

Описание расширения будет отображаться с помощью файла описания, соответствующего локали, которая в данный момент используется в Plesk. Если подходящий файл описания не найден в папке descriptions/, описание будет отображаться с помощью файла DESCRIPTION.md.

Вот пример файла описания для расширения, выпущенного Plesk. Вы можете использовать его для справки.

To help you meet the evolving requirements of your customers, Plesk Onyx comes with Docker support.
Here is what you can do with it:

 - Have on-demand access to a wide range of modern technologies,
   such as redis, mongodb, memcached, and many more.
 - Choose from a catalog of available images, or upload a custom image.
 - Deploy and manage Docker containers straight from the Plesk interface.
 - Install Docker containers locally, or to a remote node registered in Plesk.

[Learn More](https://docs.plesk.com/en-US/current/administrator-guide/web-hosting/using-docker.75823/)

*This extension is **FREE** with Plesk. You can also get remote node support for only $5.00 a month.*

CHANGES.md

Прежде чем загрузить расширение, администраторы Plesk хотят видеть, какие изменения добавились в последних обновлениях расширения. Они также могут захотеть увидеть информацию об устранении той или иной неисправности.

Используйте файл CHANGES.md, чтобы сообщить администраторам Plesk о том, какие изменения вы вносите в расширение, включая следующие изменения (но не ограничиваясь ими):

  • Изменения в дизайне.
  • Новые и улучшенные функции.
  • Исправленные ошибки и решенные проблемы.
  • Изменения в ценовой политике.

Информация из файла CHANGES.md отображается в тот момент, когда администратор Plesk нажимает имя расширения в каталоге расширений.

Вот пример содержимого файла CHANGES.md для расширения, выпущенного Plesk. Вы можете использовать его для справки.

# 1.3.0

* [*] Docker is supported on Virtuozzo 7 and separate Virtuozzo Application
  templates are now available for Plesk Docker.

# 1.2

* [*] Docker extension installation hung on Linode servers with Ubuntu 16.04.
  (EXTDOCKER-25)

# 1.1

* [-] Incorrect hint was displayed in the Environmental variable value field
  in a container's settings. (EXTDOCKER-19)

* [-] In the case of using a remote Docker, no hint was displayed for the SSL
  icon on the "Tools & Settings > Docker" page. (EXTDOCKER-8)

* [-] HTML tags were displayed in the Plesk search results for the found
  Docker Catalog location. (EXTDOCKER-6)

* [-] When a Docker proxy rule was deleted from the domain's Proxy Rules page
  and from Websites & Domains, different confirmation dialogs were displayed.
  (EXTDOCKER-2)

Значки и снимки экрана (_meta/)

Папка /_meta/ в корневой папке расширения содержит значки и снимки экрана расширения.

Значки

Значки расширения отображаются в разных частях интерфейса Plesk. Пожалуйста, придерживайтесь следующих правил при проектировании и создании значков для вашего расширения:

  1. Изображение должно занимать как можно большую часть рабочей области значка.
  2. Изображение должно быть расположено в центре рабочей области значка.
  3. Фон значка должен быть прозрачным.

image 78985

Значки должны иметь формат PNG и быть доступны в следующих размерах.

Размер Расположение
32 пикс * 32 пикс _meta/icons/32x32.png
64 пикс * 64 пикс _meta/icons/64x64.png
128 пикс * 128 пикс _meta/icons/128x128.png
Только для платных расширений: 160 пикс * 160 пикс _meta/icons/160x160.png

Снимки экрана

Снимки экрана сопровождают описание расширения на странице обзора расширения. Они должны иметь формат PNG. Можно создать до трех снимков экрана.

Примечание: Должен быть доступен хотя бы один снимок экрана.

Размер Расположение
1024 px * 768 px

_meta/screenshots/1.png (обязательно)

_meta/screenshots/2.png (необязательно)

_meta/screenshots/3.png (необязательно)

Разрешение конфликтов при обновлении

Когда администратор загружает новую версию расширения в Plesk, возможные конфликты между существующими и новыми файлами разрешаются следующим образом:

  • Если файл уже существует, он перезаписывается.
  • Если папка уже существует, файлы внутри нее перезаписываются.
  • Файлы, которые присутствовали в предыдущей версии расширения, но отсутствуют в новой версии, удаляются.

Если какое-либо из этих правил разрешения конфликтов не может быть выполнено (например, существующий файл заблокирован и не может быть перезаписан), процедура обновления прерывается.

Процедура удаления

При удалении расширения удаляются следующие файлы:

  • PRODUCT_ROOT_D/admin/htdocs/modules/EXTENSION_ID/
  • PRODUCT_ROOT_D/admin/plib/modules/EXTENSION_ID/
  • PRODUCT_ROOT_D/var/modules/EXTENSION_ID/

Здесь PRODUCT_ROOT_D — это /usr/local/psa на системах Linux и %plesk_dir% — на системах Windows.

Если расширение не может быть удалено, процедура удаления прерывается.

Все файлы, используемые расширением, должны быть удалены с помощью скрипта pre-uninstall.